README: code that runs as copied, a quick start and C# tasks; NuGet packs the same README by tomasr78 · Pull Request #83 · ConvertAPI/convertapi-library-dotnet

tomasr78 · 2026-11-07T14:11:03Z

Rewrites README.md so its code runs as copied, adds a quick start and a free-token link, uses C# task wording, and makes the repository README the one that nuget.org shows. No SDK code changes; those come in 3.3.0.

What changes

README.md: new top, a quick start, a task table, "... in C#" sections for 8 tasks, every snippet a complete program, a security section. Details below.
One README for GitHub and NuGet. ConvertApi/ConvertApi.csproj packs ../README.md as README.md. The drifted ConvertApi/docs/README.md is deleted.
.github/workflows/publish.yml: a step before "Build and pack" rewrites utm_source=github to utm_source=nuget in the run's checkout, so the packed copy's sign-up links are tagged for nuget.org. "Check the package" now fails if the packed README.md is missing or still says utm_source=github.
RELEASING.md (step 3) and CHANGELOG.md ([Unreleased]) describe both.
main merged in on 2026-11-09, bringing Fix SaveFileAsync keeping old bytes when it overwrites a longer file #84. The only conflict was in CHANGELOG.md, where both branches had opened ## [Unreleased]. It is now one section: Fix SaveFileAsync keeping old bytes when it overwrites a longer file #84's Fixed entry, then one Changed list with Fix SaveFileAsync keeping old bytes when it overwrites a longer file #84's two entries first and this PR's two after them.

Before and after

	Before (`main`, 510 lines)	After
Top	"ConvertAPI C# Client", an overview paragraph, a 29-bullet feature list	H1 "ConvertAPI C# SDK for .NET", one line naming the tasks, 4 badges (NuGet version, NuGet downloads, build, MIT), "Free trial: 250 conversions, no credit card. Get your API token"
First complete program	Line 482 of 510; reads `c:\source\test.docx` and saves to `c:\`	"Quick start" at line 9: `dotnet add package ConvertApi`, set `CONVERTAPI_TOKEN`, a 6-line program that converts the hosted sample DOCX to PDF in the current folder; one line each on .NET 10 file-based apps, .NET Framework and ASP.NET Core user secrets
Output folder	29 snippets save to `C:\output\` and line 493 to `c:\`. In 3.2.2, `SaveFilesAsync` never creates folders, so these throw unless the folder exists, and always on macOS and Linux	Every snippet saves to a relative `output` folder that it creates with `Directory.CreateDirectory`. 3.2.2, the version `dotnet add package ConvertApi` installs today, needs that line. With #84, `SaveFilesAsync` creates the folder itself, and the line is harmless
Snippets	3-line fragments without `using ConvertApiDotNet;` or a `convertApi` object	Every conversion snippet is a complete program that runs when pasted into `Program.cs`
Result files	`ProcessedFile[] files = result.Files;` (the type is now `ConvertApiFile`) and `SaveFilesAsync` without `await`	`ConvertApiFile[]`, awaited, plus saving one file, reading a stream and `DeleteFilesAsync`
User information	`convert.GetUserAsync()`: no such variable	`convertApi.GetUserAsync()`
PDF to JPG parameters	`ScaleImage` and `ScaleProportions`, which pdf-to-jpg ignores	`FitToSize` with `ImageWidth` and `ImageHeight`: the thumbnail fits in 300 x 300 (231 x 300 on the test PDF)
PDF/A	`pdfa2b` here, `pdfa2` in the NuGet README. The API rejects `pdfa2` with 400 Bad Request	`pdfA2b`, spelled as in the API spec
Converter names	`web` to `pdf`, `pdf` to `watermark`, `any` to `zip`, and `RotatePage` for rotation. None of these is in the current API spec at https://v2.convertapi.com/info/openapi (the first three still work on staging; the rotate parameter is `Angle`, default 90)	`html` to `pdf` with `Url`, `text-watermark`, `file` to `zip`, `Angle`
HTML to PDF	A URL only	An HTML file, an HTML string and a web page URL
Errors	"Secret is not provided or no additional seconds left in the account"	401 = token missing or invalid, 403 = no conversions left or account suspended, 503 = retry; plus the `ArgumentNullException` when the variable is not set
Calls to action	An untagged link to `/a/authentication`	The same tagged sign-up link twice: at the top and in "Set the API token". `ReturnUrl` lands new users and signed-in customers on their tokens. Tags are top-level, not inside `ReturnUrl`
Headings	"Office to PDF", "HTML/Web to PDF", ...	"... in C#" only for Word (DOCX) to PDF, HTML to PDF, Excel to PDF, PDF to Word, PDF to JPG or PNG, extract text from PDF, compress PDF and HTML to DOCX. The other task headings keep their words, so their anchors still work
Feature list	29 bullets	A task table that links each snippet and its example file by `/blob/` URL
More examples	A `/tree/` link to the Examples folder, then per-file links	The "### More examples" heading (`#more-examples`) and its per-file links from #81 are kept; the `/tree/` link is gone
Compatibility	Above Usage; lists Xamarin and UWP	Below Usage; without them
Security	None	"Security, data and support": files stored at most 3 hours, `DeleteFilesAsync`, encryption, server locations, compliance, status and support links
Small fixes	"using a headless Chrome browser", "Refere", an http MIT link, `/doc/...` links that redirect	Engine phrase removed, typo fixed, https links, final `/docs/...` URLs
nuget.org	`ConvertApi/docs/README.md`: H1 "ConvertAPI NuGet Package", "C#" 0 times, no example links, `pdfa2`	The repository README, with `utm_source=nuget`

All links are absolute https URLs, except in-page anchors. nuget.org renders those too: its current page has heading ids and working #... links. The badges use img.shields.io, which nuget.org allows. The README is plain ASCII and uses no HTML.

Tested snippets

Every C# block in the new README was run on macOS with .NET SDK 10.0.401, against the staging API (https://stag-v2.convertapi.com). Each block became Program.cs of a fresh dotnet new console project with ConvertApi 3.2.2 from nuget.org, byte for byte. A separate module-initializer file pointed the SDK at staging, the way Examples/ConverterCatalogDemo sets ApiBaseUri. The output files were then checked with pdfinfo, pdftotext, qpdf, sips and unzip.

All 43 blocks passed:

README section	Input	Result
Quick start	hosted `document.docx`	`document.pdf` in the current folder (2 pages); prints its full path
Set the API token (one line)	-	compiles inside a minimal program
Set the conversion location (one line)	-	compiles; `ApiBaseUri` reads `https://eu-v2.convertapi.com`
Convert Word (DOCX) to PDF in C#	`document.docx`	`output/document.pdf`, 2 pages with the document's text
Convert HTML to PDF in C#: file	`page.html`	`output/page.pdf`, A4, with the page's text
Convert HTML to PDF in C#: string	-	`output/invoice.pdf` with "Invoice 1001"
Convert HTML to PDF in C#: URL	https://www.example.com	`output/www_example_com.pdf`, title "Example Domain"
Convert Excel to PDF in C#	`spreadsheet.xlsx`	`output/spreadsheet.pdf`
Convert PDF to Word in C#	`document.pdf` (6 pages)	`output/document.docx`
Convert PDF to JPG or PNG in C#	`document.pdf`	6 JPGs: `document.jpg`, `document-2.jpg` ... `document-6.jpg`
Extract text from PDF in C#	`document.pdf`	the text printed to the console
Compress PDF in C#	`document.pdf`, 1,086,060 bytes	246,543 bytes
Convert HTML to DOCX in C#	`page.html`	`output/page.docx` with the page's heading
PowerPoint to PDF	`presentation.pptx`	7 pages
Image to PDF	`image.jpg`	1 page
PDF to PowerPoint	`document.pdf`	6 slides
eBook conversion	`book.epub`	160 pages
Email conversion	`email.eml`	`output/email.pdf`
Merge documents	`first.pdf` (6 pages), `second.pdf` (1)	7 pages
Split PDF	`document.pdf`	6 files
Rotate pages	`document.pdf`	pages rotated 90 degrees
Delete pages	`document.pdf`	6 pages to 4
Add watermark	`document.pdf`	"Confidential" on the pages
Flatten PDF	`form.pdf`, 19 form fields	0 form fields
Repair PDF	a damaged PDF	2 pages, `qpdf --check` clean
Rasterize PDF	`document.pdf`	no selectable text left, pages are images
Password protect PDF	`document.pdf`	opening needs the password
Remove PDF password	the protected PDF from the row above	not encrypted
Redact PDF	`document.pdf`	`output/document.pdf`, 6 pages
Convert to PDF/A	`document.pdf`	XMP says PDF/A part 2, conformance B
Remove metadata	`document.pdf` with an author	title, subject, author, creator and keywords empty
Extract tables from PDF	`document.pdf`	`output/document.xlsx`
Extract images from PDF	`document.pdf`	18 PNG files
Extract form data	`form.pdf`	`output/form.fdf`
Extract email attachments	`email.eml`	the attached file
Generate document from template	`template.docx` with `{{name}}`	PDF reads "Hello John"
Compare documents	`original.docx`, `revised.docx`	DOCX with 144 insertions and 115 deletions as tracked changes
Create ZIP archive	`document.pdf`, `document.docx`	`output/document.zip` with both files
Work with the result	`document.pdf`	cost and 6 files printed, 6 JPGs and `first-page.jpg` saved, server files deleted
Convert a file from a URL	hosted `presentation.pptx`	38 pages
Additional conversion parameters	`document.pdf`	`output/document.jpg`, 231 x 300 pixels
Handle errors	`document.docx`	`output/document.pdf`; with an invalid token it prints the 401 line
User information	-	prints "Conversions used: N of M"

Also run:

.NET 10 file-based app: #:package ConvertApi@* plus the quick start, with one test-only line pointing at staging, saved document.pdf. #:package ConvertApi without a version fails with NU1015, so the note says @*.
ASP.NET Core note: dotnet new web, dotnet user-secrets init, dotnet user-secrets set ConvertApi:Token ... and new ConvertApi(builder.Configuration["ConvertApi:Token"]) converted a file on staging. set fails without init, so the note has both.
.NET Framework note: the quick start inside static async Task Main(), with using System; and using System.Threading.Tasks;, compiles for net48 with C# 7.3. Not run: there is no Mono on this Mac.
Side claims: a .doc file with "docx" converts; "png" in place of "jpg" gives PNG pages; an .msg file with "eml" converts; non-ASCII text in the HTML string survives without a <meta charset>; DeleteFilesAsync deleted 7 files (6 results and the upload); an invalid token prints 401 Unauthorized: {"Code":4011,"Message":"Unauthorized. Invalid or missing API credentials."}.
Conversion location: the line compiles and sets the address; https://eu-v2.convertapi.com/user answers 401 without a token. Nothing was converted on production.
Against the merged main, with Fix SaveFileAsync keeping old bytes when it overwrites a longer file #84: after the merge, the library was packed from this branch as 3.3.0-local.pr83 into a local feed, and all 43 blocks were run again on staging against it. All 43 passed, and every output check matched the 3.2.2 run. The merged tree also passes the build check's steps: restore, a build of all 23 projects, the 4 unit tests and pack. Its only 3 warnings come from two examples this PR does not touch (ConverterCatalogDemo, GetConverterInfoDemo).

Package

dotnet pack: README.md sits at the package root, byte-identical to the repository's README.md, and the nuspec has <readme>README.md</readme>. The NU5048 PackageIconUrl warning was already there; 3.3.0 replaces the icon.
The publish steps, run by hand on a copy: the retag step turns both sign-up links into utm_source=nuget, and the new check passes. The check fails (exit 1) on a package packed without the retag, and on one without a README.
After the merge with main, the pack result is the same: README.md at the package root, byte-identical to the repository's.

Not in this PR

SDK fixes planned for 3.3.0 that are not on main yet: the SDK reading CONVERTAPI_TOKEN, clearer 401 and 403 messages, the package icon. Two of the planned fixes, SaveFilesAsync creating its folder and SaveFileAsync replacing a longer file, are on main since Fix SaveFileAsync keeping old bytes when it overwrites a longer file #84.
The examples still use names that are not in the current API spec: web (ConvertUrlToPdf), watermark and watermark-overlay (WatermarkPdf), jpg to zip (Workflow). web and watermark still work on staging; the other two were not tried. CreatePdfThumbnail is fixed in PDF thumbnail example: fix the comment, keep the thumbnail inside 300x300 #82.

🤖 Generated with Claude Code

…Get packs it - README.md: a quick start (dotnet add package, CONVERTAPI_TOKEN, a 6-line program on a hosted sample), a task table, "... in C#" sections for 8 tasks, every snippet a complete program that saves to a relative output folder it creates, ConvertApiFile, FitToSize, the current converter names, the 401, 403 and 503 codes, and a security, data and support section. - ConvertApi.csproj packs the root README.md; the drifted ConvertApi/docs/README.md is deleted. - publish.yml rewrites utm_source=github to utm_source=nuget in the packed copy and fails if the packed README.md is missing or still says github. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot

🟢 Approval recommended

No active review issues are recorded for the documentation and shared README packaging changes.

No open issues 🎉

What changed in this PR

Improves the .NET SDK’s onboarding documentation and uses one README for both GitHub and NuGet, without changing SDK implementation code.

Changes:

Adds a quick start, task navigation, complete C# conversion examples, and security guidance.
Packages the repository README and removes the separate NuGet copy.
Updates publishing to retag README links for NuGet and validate the packaged README.

File	Description
`RELEASING.md`	Documents the shared README and NuGet link tagging.
`README.md`	Reworks setup, task examples, error handling, and security guidance.
`ConvertApi/docs/README.md`	Removes the duplicated NuGet README.
`ConvertApi/ConvertApi.csproj`	Packs the repository README at the package root.
`CHANGELOG.md`	Records the documentation and packaging changes.
`.github/workflows/publish.yml`	Retags links and checks the packaged README before publishing.

_{Review effort: Balanced}

Brings in #84: SaveFileAsync replaces a longer file, SaveFilesAsync creates its folder, and unit tests run in the build check. The only conflict was CHANGELOG.md, where both branches opened [Unreleased]. It is now one section: #84's Fixed entry, then one Changed list with #84's entries first and this branch's after them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot

🟡 Changes recommended

The README’s hard-coded .NET 10 output path can cause FileNotFoundException with other target frameworks or debugger working directories and should instead reference the configured working directory.

1 open issue

Use the debugger's working directory for the input file · New

_{Review effort: Balanced}

…t net10.0 The README said a program started from Visual Studio runs in bin\Debug\net10.0. That holds only for a .NET 10 project with default settings: the README also covers .NET 5 to 9, .NET Core and .NET Framework, whose output folders differ, and the debug launch profile can set another working directory. The note now names the launch profile's working directory and gives the build output folder as its default. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot

🟢 Approval recommended

No active review issues remain for the documentation and packaging changes.

No open issues 🎉

1 resolved since last review

Use the debugger's working directory for the input file

_{Review effort: Balanced}

Copilot AI balanced review requested due to automatic review settings November 7, 2026 14:11

Copilot started reviewing on behalf of tomasr78 November 7, 2026 14:11

View session

Copilot AI reviewed Nov 7, 2026

View reviewed changes

tomasr78 mentioned this pull request Nov 9, 2026

Fix SaveFileAsync keeping old bytes when it overwrites a longer file #84

Merged

Copilot AI balanced review requested due to automatic review settings November 9, 2026 08:33

Copilot started reviewing on behalf of tomasr78 November 9, 2026 08:34

View session

Copilot AI reviewed Nov 9, 2026

View reviewed changes

Comment thread README.md Resolved

Copilot AI balanced review requested due to automatic review settings November 9, 2026 08:39

Copilot started reviewing on behalf of tomasr78 November 9, 2026 08:40

View session

Copilot AI reviewed Nov 9, 2026

View reviewed changes

tomasr78 mentioned this pull request Nov 9, 2026

Examples: read the token from CONVERTAPI_TOKEN and find the sample files from any folder #85

Merged

kostas-jonauskas approved these changes Nov 9, 2026

View reviewed changes

kostas-jonauskas merged commit 362ac47 into main Nov 9, 2026
2 checks passed

kostas-jonauskas deleted the readme-quick-start branch November 9, 2026 10:29

This was referenced Nov 9, 2026

README pdf-to-jpg snippet without ScaleImage/ScaleProportions ConvertAPI/convertapi-library-js#30

Merged

README: link Examples/README.md from the More examples section #90

Merged

Navigation Menu

Repository navigation

README: code that runs as copied, a quick start and C# tasks; NuGet packs the same README - #83

README: code that runs as copied, a quick start and C# tasks; NuGet packs the same README#83
kostas-jonauskas merged 3 commits into
mainfrom
readme-quick-start

tomasr78 commented Nov 7, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

tomasr78 commented Nov 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changes

Before and after

Tested snippets

Package

Not in this PR

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tomasr78 commented Nov 7, 2026 •

edited

Loading